//! \file CMutex.h
//! \brief Implements mutual exclusion between multiple processes for the
//! Linux operating system.
//!
//! A mutex provides mutual exclusion to critical sections between multiple
//! threads.  A critical section typically contains access to a shared
//! resource that must be allowed to complete without interruption.
// -----------------------------------------------------------------------------
//! This program is free software; you can redistribute it and/or
//! modify it under the terms of the GNU General Public License
//! as published by the Free Software Foundation; either version 2
//! of the License, or (at your option) any later version.
//!
//! This program is distributed in the hope that it will be useful,
//! but WITHOUT ANY WARRANTY; without even the implied warranty of
//! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//! GNU General Public License for more details.
//!
//! You should have received a copy of the GNU General Public License
//! along with this program; if not, write to the Free Software Foundation,
//! Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
// -----------------------------------------------------------------------------

// Project Includes
#include "Config.h"
#include "IMutex.h"

// Standard Includes
#include <pthread.h>

#ifndef dCMUTEX_H_
  #define dCMUTEX_H_

  namespace code_sheriff
  {

    //! \class CMutex CMutex.h "CMutex.h"
    //! \brief Provides mutual exclusion to critical sections.
    //!
    //! A mutex provides mutual exclusion to critical sections between multiple
    //! threads.  A critical section typically contains access to a shared
    //! resource that must be allowed to complete without interruption.
    class CMutex : public IMutex
    {

      //========================================================================
      public:
      //========================================================================

        //! \brief Class constructor.
        //!
        //! This is the class constructor.  The constructor instantiates an
        //! object instance of the class and initializes the instance for use.
        //!
        //! \b Example: \code
        //! CMutex* pMutex = new CMutex();
        //! \endcode
        CMutex();

        //! \brief Class destructor.
        //!
        //! This is the class destructor.  The destructor destroys an object
        //! instance of the class and deallocates any memory that was used.
        //!
        //! \b Example: \code
        //! CMutex* pMutex = new CMutex();
        //! delete pMutex;
        //! \endcode
        virtual ~CMutex();

        //! \brief Requests mutual exclusion.
        //!
        //! Allows the calling process to attempt to gain mutual exclusion.
        //! When mutual exclusion is granted, the process can safely access the
        //! critical section.
        //!
        //! \param [in] Timeout
        //!   The maximum time interval (in milliseconds) to block the calling
        //!   process for while waiting for the lock to become available.
        //!
        //! \retval Error
        //!   Error code indicating the result of the requested operation.
        //!
        //! \b Example: \code
        //! CMutex MyMutex;
        //! MyMutex.lock(TIMEOUT_IMMEDIATELY);
        //! \endcode
        TERROR lock(tTIME_MS Timeout);

        //! \brief Requests mutual exclusion.
        //!
        //! Allows the calling process to attempt to gain mutual exclusion.
        //! When mutual exclusion is granted, the process can safely access the
        //! critical section.
        //!
        //! \retval Error
        //!   Error code indicating the result of the requested operation.
        //!
        //! \b Example: \code
        //! CMutex MyMutex;
        //! MyMutex.lock(TIMEOUT_FOREVER);
        //! ... <access memory> ...
        //! MyMutex.unlock();
        //! \endcode
        TERROR unlock(void);

      //========================================================================
      private:
      //========================================================================

        //! \brief Mutex object native to the implementing operating system.
        //!
        //! As mutex implementations vary among operating systems, this defines
        //! our actual mutex object for the specific operating system being
        //! built on.
        pthread_mutex_t m_Mutex;
    };

  } // namespace code_sheriff

#endif // dCMUTEX_H_
